</> 技術筆記Tech Notes

DXCore 系列： 輕鬆搞定 JavaScript 日期處理

· 軟體專案/DXCore - JavaScript 程式庫 javascript

在軟體開發中，處理日期和時間是相當常見但又容易出錯的任務。JavaScript 原生的 Date 物件雖然功能強大，但在格式化、日期計算和解析方面，其 API 有時顯得不夠直觀。

為了解決這些痛點，DXCore 解決方案套件中包含了強大的 日期工具 模組。本文將以這個實用的模組為例，帶您深入了解如何優雅地處理日期的核心技巧。

一、為什麼需要專門的日期工具？

直接使用 JavaScript 的 Date 物件常會遇到以下挑戰：

  • 格式化困難：沒有內建方法能直接將日期轉換為 YYYY-MM-DD 這類自訂格式。

  • 日期計算複雜：處理跨月份、跨年份或閏年的增減時，需要編寫繁瑣的邏輯。

  • 解析不穩定：new Date('...') 的解析行為在不同瀏覽器和 JavaScript 引擎之間可能存在差異。

DXCore 的 日期工具 模組將這些複雜操作封裝成簡單、易讀的方法，顯著提升了程式碼的可讀性和維護性。

二、DXCore 日期工具 核心功能解析

日期工具 是 DXCore 中的一個 JavaScript 類別，它封裝了多種實用的日期處理方法。

1. 日期格式化 (格式化日期)

這是最常用的功能之一。格式化日期 方法可以將一個 Date 物件，依照指定的格式字串，轉換成容易閱讀的日期字串。

支援的格式符號包括：

  • YYYY: 四位數年份 (如 2023)

  • YY: 兩位數年份 (如 23)

  • MM: 補零的兩位數月份 (如 01, 12)

  • DD: 補零的兩位數日期 (如 01, 31)

  • HH: 補零的 24 小時制小時 (如 01, 23)

  • mm: 補零的分鐘 (如 01, 59)

  • ss: 補零的秒數 (如 01, 59)

  • DOW: 完整的中文星期 (如 星期日)

  • dow: 簡短的中文星期 (如 日)

範例：

import {日期工具} from 'dx-core';
const date = new Date('2023-11-01T14:30:59');

// 格式化為 YYYY-MM-DD 格式
const formattedDate = 工具.格式化日期(date, 'YYYY-MM-DD HH:mm:ss');
console.log(formattedDate); // 返回 '2023-11-01 14:30:59'

// 格式化為中文星期格式
const weekDay = 工具.格式化日期(date, '今天是DOW');
console.log(weekDay); // 返回 '今天是星期三'

2. 日期計算 (加上 與 減去)

在日期上增加或減少天數、月份、年份是常見需求。加上 和 減去 方法讓這項工作變得非常簡單。

範例：

import {日期工具} from 'dx-core';
const date = new Date('2023-11-15');

// 新增 2 個月
const futureDate = 工具.加上(date, 'month', 2);
console.log(工具.格式化日期(futureDate, 'YYYY-MM-DD')); // '2024-01-15'

// 減去 10 天
const pastDate = 工具.減去(date, 'day', 10);
console.log(工具.格式化日期(pastDate, 'YYYY-MM-DD')); // '2023-11-05'

此模組巧妙地利用 Units 物件來定義可操作的時間單位，這體現了 DXCore 對程式碼穩定性和可維護性的重視。

3. 日期解析與驗證 (解析 與 是否為有效日期字串)

除了將日期物件轉為字串，反向操作（從字串解析為日期）也同樣重要。DXCore 的 日期工具 提供了比原生 new Date() 更為精確可靠的解析方法。

範例：

import {日期工具} from 'dx-core';

// 驗證
console.log(工具.是否為有效日期字串('2023-11-30')); // true
console.log(工具.是否為有效日期字串('not-a-date')); // false

// 根據指定格式解析
try {
    const date = 工具.解析('2023-11-15 14:30', 'YYYY-MM-DD hh:mm');
    console.log(date); // 返回 Date 物件
} catch (error) {
    console.error(error.message); // 如果格式不符，會拋出錯誤
}

4. 日期比較 (在範圍內)

在範圍內 方法可以輕鬆判斷一個日期是否落在另外兩個日期之間（包含開始和結束日期）。

範例：

import {日期工具} from 'dx-core';
const date = new Date('2023-11-15');
const start = new Date('2023-11-01');
const end = new Date('2023-11-30');

console.log(工具.在範圍內(date, start, end)); // true

此方法還包含了邊界檢查，例如起始日期不能晚於結束日期，確保了函式的穩健性。

5. 資訊提取 (提取 與 取得中文星期名稱)

有時候我們只需要日期中的特定部分，例如年份或星期幾。

範例：

import {日期工具} from 'dx-core';
const date = new Date('2023-11-01'); // 這天是星期三

// 提取日期組件
const parts = 工具.提取(date);
console.log(parts.year);  // 2023
console.log(parts.month); // 10 (月份從 0 開始)

// 取得星期
console.log(工具.取得中文星期名稱(date));      // '星期三'

三、從範例中學到的 DXCore 設計哲學

DXCore 的 日期工具 模組不僅功能實用，其程式碼結構也體現了良好的設計哲學：

  • 類別封裝 (Class Encapsulation): 將所有相關功能都封裝在 日期工具 類別中，結構清晰，易於管理和使用。

  • 單一職責原則: 每個方法都只專注於一項任務，增加了程式碼的模組化程度。

  • 明確的錯誤處理: 對於無效的輸入，方法會拋出 Error，讓開發者能清楚地知道問題所在並進行處理。

結論

通過分析 DXCore 的 日期工具 模組，我們不僅學會了如何解決 JavaScript 中常見的日期操作難題，更重要的是，我們看到了一個追求穩定、易用和高可讀性的工程實踐。下次當您需要處理日期時，不妨考慮使用 DXCore 套件，讓繁瑣的日期操作變得輕鬆愉快。